flex player Camera, microphone, clipboard, mouse, and keyboard access
When a SWF file attempts to access a user's camera or microphone using the Camera.get() or Microphone.get() methods, Flash Player displays a Privacy dialog box, in which the user can allow or deny access to their camera and microphone. The user and the administrative user can also disable camera access on a per-site or global basis, through controls in the mms.cfg file, the Settings UI, and the Settings Manager (see Administrative user controls and User controls). With user restrictions, the Camera.get() and Microphone.get() methods each return a null value. You can use the Capabilities.avHardwareDisable property to determine whether the camera and microphone have been administratively prohibited (true) or allowed (false).
The System.setClipboard() method allows a SWF file to replace the contents of the clipboard with a plain-text string of characters. This poses no security risk. To protect against the risk posed by passwords and other sensitive data being cut or copied to clipboards, there is no corresponding "getClipboard" (read) method.
A Flash application can monitor only keyboard and mouse events that occur within its focus. A Flash application cannot detect keyboard or mouse events in another application.
Shared objects
Flash Player provides the ability to use shared objects, which are ActionScript objects that persist outside of a SWF file, either locally on a user's file system or remotely on an RTMP server. Shared objects, like other media in Flash Player, are partitioned into security sandboxes. However, the sandbox model for shared objects is somewhat different, because shared objects are not resources that can ever be accessed across domain boundaries. Instead, shared objects are always retrieved from a shared object store that is particular to the domain of each SWF file that calls methods of the SharedObject class. Usually a shared object store is even more particular than a SWF file's domain: by default, each SWF file uses a shared object store particular to its entire origin URL.
A SWF file can use the localPath parameter of the SharedObject.getLocal() and SharedObject.getRemote() methods to use a shared object store associated with only a part of its URL. In this way, the SWF file can permit sharing with other SWF files from other URLs. Even if you pass '/' as the localPath parameter, this still specifies a shared object store particular to its own domain.
Users can restrict shared object access by using the Flash Player Settings dialog box or the Settings Manager. By default, shared objects can be created up to a maximum of 100 KB of data per domain. Administrative users and users can also place restrictions on the ability to write to the file system. For more information, see Administrative user controls and User controls.
You can specify that a shared object is secure, by specifying true for the secure parameter of the SharedObject.getLocal() method or the SharedObject.getRemote() method. Note the following about the secure parameter:
- If this parameter is set to true, Flash Player creates a new secure shared object or gets a reference to an existing secure shared object. This secure shared object can be read from or written to only by SWF files delivered over HTTPS that call SharedObject.getLocal() with the secure parameter set to true.
- If this parameter is set to false, Flash Player creates a new shared object or gets a reference to an existing shared object that can be read from or written to by SWF files delivered over non-HTTPS connections.
If the calling SWF file is not from an HTTPS URL, specifying true for the secure parameter of the SharedObject.getLocal() method or the SharedObject.getRemote() method results in a SecurityError exception.
The choice of a shared object store is based on a SWF file's origin URL. This is true even in the two situations where a SWF file does not originate from a simple URL: import loading and dynamic loading. Import loading refers to the situation where you load a SWF file with the LoaderContext.securityDomain property set to SecurityDomain.currentDomain. In this situation, the loaded SWF file will have a pseudo-URL that begins with its loading SWF file's domain and then specifies its actual origin URL. Dynamic loading refers to the loading of a SWF file using the Loader.loadBytes() method. In this situation, the loaded SWF file will have a pseudo-URL that begins with its loading SWF file's full URL followed by an integer ID. In both the import loading and dynamic loading cases, a SWF file's pseudo-URL can be examined using the LoaderInfo.url property. The pseudo-URL is treated exactly like a real URL for the purposes of choosing a shared object store. You can specify a shared object localPath parameter that uses part or all of the pseudo-URL.
Users and administrators can elect to disable the use of third-party shared objects. This is the usage of shared objects by any SWF file that is executing in a web browser, when that SWF file's origin URL is from a different domain than the URL shown in the browser's address bar. Users and administrators may choose to disable third-party shared object usage for reasons of privacy, wishing to avoid cross-domain tracking. In order to avoid this restriction, you may wish to ensure that any SWF file using shared objects is loaded only within HTML page structures that ensure that the SWF file comes from the same domain as is shown in the browser's address bar. When you attempt to use shared objects from a third-party SWF file, and third-party shared object use is disabled, the SharedObject.getLocal() and SharedObject.getRemote() methods return null. For more information, see www.adobe.com/products/flashplayer/articles/thirdpartylso.
flex player Controlling access to scripts in a host web page
Outbound scripting is achieved through use of the following ActionScript 3.0 APIs:
- The flash.system.fscommand() function
- The flash.net.navigateToURL() function (when specifying a scripting statement, such as navigateToURL("javascript: alert('Hello from Flash Player.')")
- The flash.net.navigateToURL() function (when the window parameter is set to "_top", "_self", or "_parent")
- The ExternalInterface.call() method
For SWF files running locally, calls to these methods are successful only if the SWF file and the containing web page (if there is one) are in the local-trusted security sandbox. Calls to these methods fail if the content is in the local-with-networking or local-with-filesystem sandbox.
The AllowScriptAccess parameter in the HTML code that loads a SWF file controls the ability to perform outbound scripting from within a SWF file.
Set this parameter in the HTML code for the web page that hosts a SWF file. You set the parameter in the PARAM or EMBED tag.
The AllowScriptAccess parameter can have one of three possible values: "always", "sameDomain", or "never":
- When AllowScriptAccess is "sameDomain", outbound scripting is allowed only if the SWF file and the web page are in the same domain. This is the default for AVM2 content.
- When AllowScriptAccess is "never", outbound scripting always fails.
- When AllowScriptAccess is "always", outbound scripting always succeeds.
If the AllowScriptAccess parameter is not specified for a SWF file in an HTML page, it defaults to "sameDomain" for AVM2 content.
Here is an example of setting the AllowScriptAccess tag in an HTML page:
The AllowScriptAccess parameter can prevent a SWF file hosted from one domain from accessing a script in an HTML page that comes from another domain. Using AllowScriptAccess="never" for all SWF files hosted from another domain can ensure the security of scripts located in an HTML page.
For more information, see the following entries in the ActionScript 3.0 Language and Components Reference:
- The flash.system.fscommand() function
- The flash.net.navigateToURL() function
- The call() method of the ExternalInterface class
Setting LocalConnection permissions
The LocalConnection class lets you develop SWF files that can send instructions to each other. LocalConnection objects can communicate only among SWF files that are running on the same client computer, but they can be running in different applications--for example, a SWF file running in a browser and a SWF file running in a projector.
For every LocalConnection communication, there is a sender SWF file and a listener SWF file. By default, Flash Player allows LocalConnection communication between SWF files in the same domain. For SWF files in different sandboxes, the listener must allow the sender permission by using the LocalConnection.allowDomain() method. The string you pass as an argument to the LocalConnection.allowDomain() method can contain any of the following: exact domain names, IP addresses, and the * wildcard.
A SWF file can use the domain property of the LocalConnection class to determine its domain.
Working with legacy content
In Flash Player 6, the domain that is used for certain Flash Player settings is based on the trailing portion of the domain of the SWF file. These settings include settings for camera and microphone permissions, storage quotas, and storage of persistent shared objects.
If the domain of a SWF file includes more than two segments, such as www.example.com, the first segment of the domain (www) is removed, and the remaining portion of the domain is used. So, in Flash Player 6, www.example.com and store.example.com both use example.com as the domain for these settings. Similarly, www.example.co.uk and store.example.co.uk both use example.co.uk as the domain for these settings. This can lead to problems in which SWF files from unrelated domains, such as example1.co.uk and example2.co.uk, have access to the same shared objects.
In Flash Player 7 and later, player settings are chosen by default according to a SWF file's exact domain. For example, a SWF file from www.example.com would use the player settings for www.example.com. A SWF file from store.example.com would use the separate player settings for store.example.com.
In a SWF file written using ActionScript 3.0, when Security.exactSettings is set to true (the default), Flash Player uses exact domains for player settings. When it is set to false, Flash Player uses the domain settings used in Flash Player 6. If you change exactSettings from its default value, you must do so before any events occur that require Flash Player to choose player settings--for example, using a camera or microphone, or retrieving a persistent shared object.
If you published a version 6 SWF file and created persistent shared objects from it, to retrieve those persistent shared objects from a SWF that uses ActionScript 3.0, you must set Security.exactSettings to false before calling SharedObject.getLocal().
Loading embedded content from SWF files imported into a security domain
When you load a SWF file, you can set the context parameter of the load() method of the Loader object that is used to load the file. This parameter takes a LoaderContext object. When you set the securityDomain property of this LoaderContext object to Security.currentDomain, Flash Player checks for a cross-domain policy file on the server of the loaded SWF file. If there is a cross-domain policy file, and it grants access to the domain of the loading SWF file, you can load the SWF file as imported media. In this way, the loading file can get access to objects in the library of the SWF file.
An alternative way for a SWF file to access classes in loaded SWF files from a different security sandbox is to have the loaded SWF file call the Security.allowDomain() method to grant access to the domain of the calling SWF file. You can add the call to the Security.allowDomain() method to the constructor method of the main class of the loaded SWF file, and then have the loading SWF file add an event listener to respond to the init event dispatched by the contentLoaderInfo property of the Loader object. When this event is dispatched, the loaded SWF file has called the Security.allowDomain() method in the constructor method, and classes in the loaded SWF file are available to the loading SWF file. The loading SWF file can retrieve classes from the loaded SWF file by calling Loader.contentLoaderInfo.applicationDomain.getDefinition().
flex Loading data
SWF files can load data from servers into ActionScript, and send data from ActionScript to servers. Loading data is a different kind of operation from loading media, because the loaded information appears directly in ActionScript, rather than being displayed as media. Generally, SWF files may load data from their own domains. However, they usually require cross-domain policy files in order to load data from other domains.
Using URLLoader and URLStream
You can load data, such as an XML file or a text file. The load() methods of the URLLoader and URLStream classes are governed by cross-domain policy file permissions.
If you use the load() method to load content from a domain other than that of the SWF file that is calling the method, Flash Player checks for a cross-domain policy file on the server of the loaded assets. If there is a cross-domain policy file, and it grants access to the domain of the loading SWF file, you can load the data.
Connecting to sockets
Cross-domain access to socket and XML socket connections is disabled by default. Also disabled by default is access to socket connections in the same domain as the SWF file on ports lower than 1024. You can permit access to these ports by serving a cross-domain policy file from any of the following locations:
- The same port as the main socket connection
- A different port
- An HTTP server on port 80 in the same domain as the socket server
If you serve the cross-domain policy file from same port as the main socket connection, or in a different port, you enumerate permitted ports by using a to-ports attribute in the cross-domain policy file, as the following example shows:
To retrieve a socket policy file from the same port as a main socket connection, simply call the Socket.connect() or XMLSocket.connect() method, and, if the specified domain is not the same as the domain of the calling SWF file, Flash Player automatically attempts to retrieve a policy file from the same port as the main connection you are attempting. To retrieve a socket policy file from a different port on the same server as your main connection, call the Security.loadPolicyFile() method with the special "xmlsocket" syntax, as in the following:
Security.loadPolicyFile("xmlsocket://server.com:2525");
Call the Security.loadPolicyFile() method before calling the Socket.connect() or XMLSocket.connect() method. Flash Player then waits until it has fulfilled your policy file request before deciding whether to allow your main connection.
If you are implementing a socket server and you need to provide a socket policy file, decide whether you will provide the policy file using the same port that accepts main connections, or using a different port. In either case, your server must wait for the first transmission from your client before deciding whether to send a policy file or set up a main connection. When Flash Player requests a policy file, it always transmits the following string as soon as a connection is established:
Once the server receives this string, it can transmit the policy file. Do not expect to reuse the same connection for both a policy file request and a main connection; you should close the connection after transmitting the policy file. If you do not, Flash Player closes the policy file connection before reconnecting to set up the main connection.
For more information, see Socket policy files.
Sending data
Data sending occurs when ActionScript code from a SWF file sends data to a server or resource. Sending data is always permitted for network domain SWF files. A local SWF file can send data to network addresses only if it is in the local-trusted or local-with-networking sandbox. For more information, see Local sandboxes.
You can use the flash.net.sendToURL() function to send data to a URL. Other methods also send requests to URLs. These include loading methods, such as Loader.load() and Sound.load(), and data-loading methods, such as URLLoader.load() and URLStream.load().
Uploading and downloading files
The FileReference.upload() method starts the upload of a file selected by a user to a remote server. You must call the FileReference.browse() or FileReferenceList.browse() method before calling the FileReference.upload() method.
Calling the FileReference.download() method opens a dialog box in which the user can download a file from a remote server.
Uploads and downloads are not allowed if the calling SWF file is in the local-with-filesystem sandbox.
By default, a SWF file may not initiate an upload to, or a download from, a server other than its own. A SWF file may upload to, or download from, a different server if that server provides a cross-domain policy file that grants permission to the domain of the invoking SWF file.
flex Accessing loaded media as data
You access loaded data using methods such as BitmapData.draw() and SoundMixer.computeSpectrum(). By default, a SWF file from one security sandbox cannot obtain pixel data or audio data from graphic or audio objects rendered or played by loaded media in another sandbox. However, you can use the following methods to grant this permission:
In a loaded SWF file, call the Security.allowDomain() method to grant data access to SWF files in other domains.
For a loaded image, sound, or video, add a cross-domain policy file on the server of the loaded file. This policy file must grant access to the domain of the SWF file that is attempting to call the BitmapData.draw() or SoundMixer.computeSpectrum() methods to extract data from the file.
The following sections provide details on accessing bitmap, sound, and video data.
Subtopics
Accessing bitmap data
Accessing sound data
Accessing video data
Accessing bitmap data
The draw() method of a BitmapData object lets you draw the currently displayed pixels of any display object to the BitmapData object. This could include the pixels of a MovieClip object, a Bitmap object, or any display object. The following conditions must be met for the draw() method to draw pixels to the BitmapData object:
In the case of a source object other than a loaded bitmap, the source object and (in the case of a Sprite or MovieClip object) all of its child objects must come from the same domain as the object calling the draw() method, or they must be in a SWF file that is accessible to the caller by having called the Security.allowDomain() method.
In the case of a Loaded bitmap source object, the source object must come from the same domain as the object calling the draw() method, or its source server must include a cross-domain policy file that grants permission to the calling domain.
If these conditions are not met, a SecurityError exception is thrown.
When you load the image using the load() method of the Loader class, you can specify a context parameter, which is a LoaderContext object. If you set the checkPolicyFile property of the LoaderContext object to true, Flash Player checks for a cross-domain policy file on the server from which the image is loaded. If there is a cross-domain policy file, and the file permits the domain of the loading SWF file, the file is allowed to access data in the Bitmap object; otherwise, access is denied.
You can also specify a checkPolicyFile property in an image loaded via an tag in a text field. For details, see Loading SWF files and images using the
tag in a text field.
Accessing sound data
The following sound-related ActionScript 3.0 APIs have security restrictions:
The SoundMixer.computeSpectrum() method--Always permitted for SWF files that are in the same security sandbox as the sound file. For files in other sandboxes, there are security checks.
The SoundMixer.stopAll() method--Always permitted for SWF files that are in the same security sandbox as the sound file. For files in other sandboxes, there are security checks.
The id3 property of the Sound class--Always permitted for SWF files that are in the same security sandbox as the sound file. For files in other sandboxes, there are security checks.
Every sound has two kinds of sandboxes associated with it--a content sandbox and an owner sandbox:
The origin domain for the sound determines the content sandbox, and this determines whether data can be extracted from the sound via the id3 property of the sound and the SoundMixer.computeSpectrum() method.
The object that started the sound playing determines the owner sandbox, and this determines whether the sound can be stopped using the SoundMixer.stopAll() method.
When you load the sound using the load() method of the Sound class, you can specify a context parameter, which is a SoundLoaderContext object. If you set the checkPolicyFile property of the SoundLoaderContext object to true, Flash Player checks for a cross-domain policy file on the server from which the sound is loaded. If there is a cross-domain policy file, and the file permits the domain of the loading SWF file, the file is allowed to access the id property of the Sound object; otherwise, it will not. Also, setting the checkPolicyFile property can enable the SoundMixer.computeSpectrum() method for loaded sounds.
You can use the SoundMixer.areSoundsInaccessible() method to find out whether a call to the SoundMixer.stopAll() method would not stop all sounds because the sandbox of one or more sound owners is inaccessible to the caller.
Calling the SoundMixer.stopAll() method stops those sounds whose owner sandbox is the same as that of the caller of stopAll(). It also stops those sounds whose playback was started by SWF files that have called the Security.allowDomain() method to permit access by the domain of the SWF file calling the stopAll() method. Any other sounds are not stopped, and the presence of such sounds can be revealed by calling the SoundMixer.areSoundsInaccessible() method.
Calling the computeSpectrum() method requires that every sound that is playing be either from the same sandbox as the object calling the method or from a source that has granted permission to the caller's sandbox; otherwise, a SecurityError exception is thrown. For sounds that were loaded from embedded sounds in a library in a SWF file, permission is granted with a call to the Security.allowDomain() method in the loaded SWF file. For sounds loaded from sources other than SWF files (originating from loaded mp3 files or from Flash video), a cross-domain policy file on the source server grants access to data in loaded media. You cannot use the computeSpectrum() method if a sound is loaded from RTMP streams.
For more information, see Author (developer) controls and Website controls (cross-domain policy files).
Accessing video data
You can use the BitmapData.draw() method to capture the pixel data of the current frame of a video.
There are two different kinds of video:
RTMP video
Progressive video, which is loaded from an FLV file without an RTMP server
You cannot use the BitmapData.draw() method to access RTMP video.
When you call the BitmapData.draw() method with progressive video as the source parameter, the caller of BitmapData.draw() must either be from the same sandbox as the FLV file, or the server of the FLV file must have a policy file that grants permission to the domain of the calling SWF file. You can request that the policy file be downloaded by setting the checkPolicyFile property of the NetStream object to true.
flex Cross-scripting
If two SWF files written with ActionScript 3.0 are served from the same domain--for example, the URL for one SWF file is http://www.example.com/swfA.swf and the URL for the other is http://www.example.com/swfB.swf--then one SWF file can examine and modify variables, objects, properties, methods, and so on in the other, and vice versa. This is called cross-scripting.
Cross-scripting is not supported between AVM1 SWF files and AVM2 SWF files. An AVM1 SWF file is one created by using ActionScript 1.0 or ActionScript 2.0. (AVM1 and AVM2 refer to the ActionScript Virtual Machine.) You can, however, use the LocalConnection class to send data between AVM1 and AVM2.
If two SWF files written with ActionScript 3.0 are served from different domains--for example, http://siteA.com/swfA.swf and http://siteB.com/swfB.swf--then, by default, Flash Player does not allow swfA.swf to script swfB.swf, nor swfB.swf to script swfA.swf. A SWF file gives permission to SWF files from other domains by calling Security.allowDomain(). By calling Security.allowDomain("siteA.com"), swfB.swf gives SWF files from siteA.com permission to script it.
In any cross-domain situation, it is important to be clear about the two parties involved. For the purposes of this discussion, the side that is performing the cross-scripting is called the accessing party (usually the accessing SWF), and the other side is called the party being accessed (usually the SWF being accessed). When siteA.swf scripts siteB.swf, siteA.swf is the accessing party, and siteB.swf is the party being accessed, as the following illustration shows:
Cross-domain permissions that are established with the Security.allowDomain() method are asymmetrical. In the previous example, siteA.swf can script siteB.swf, but siteB.swf cannot script siteA.swf, because siteA.swf has not called the Security.allowDomain() method to give SWF files at siteB.com permission to script it. You can set up symmetrical permissions by having both SWF files call the Security.allowDomain() method.
In addition to protecting SWF files from cross-domain scripting originated by other SWF files, Flash Player protects SWF files from cross-domain scripting originated by HTML files. HTML-to-SWF scripting can occur with callbacks established through the ExternalInterface.addCallback() method. When HTML-to-SWF scripting crosses domains, the SWF file being accessed must call the Security.allowDomain() method, just as when the accessing party is a SWF file, or the operation will fail. For more information, see Author (developer) controls.
Also, Flash Player provides security controls for SWF-to-HTML scripting. For more information, see Controlling access to scripts in a host web page.
Subtopics
Stage security
Traversing the display list
Event security
Stage security
Some properties and methods of the Stage object are available to any sprite or movie clip on the display list.
However, the Stage object is said to have an owner: the first SWF file loaded. By default, the following properties and methods of the Stage object are available only to SWF files in the same security sandbox as the Stage owner:
Properties
Methods
align
addChild()
displayState
addChildAt()
frameRate
addEventListener()
height
dispatchEvent()
mouseChildren
hasEventListener()
numChildren
setChildIndex()
quality
willTrigger()
scaleMode
showDefaultContextMenu
stageFocusRect
stageHeight
stageWidth
tabChildren
textSnapshot
width
In order for a SWF file in a sandbox other than that of the Stage owner to access these properties and methods, the Stage owner SWF file must call the Security.allowDomain() method to permit the domain of the external sandbox. For more information, see Author (developer) controls.
The frameRate property is a special case--any SWF file can read the frameRate property. However, only those in the Stage owner's security sandbox (or those granted permission by a call to the Security.allowDomain() method) can change the property.
There are also restrictions on the removeChildAt() and swapChildrenAt() methods of the Stage object, but these are different from the other restrictions. Rather than needing to be in the same domain as the Stage owner, to call these methods code must be in the same domain as the owner of the affected child object(s), or the child object(s) can call the Security.allowDomain() method.
Traversing the display list
The ability of one SWF file to access display objects loaded from other sandboxes is restricted. In order for a SWF file to access a display object created by another SWF file in a different sandbox, the SWF file being accessed must call the Security.allowDomain() method to permit access by the domain of the accessing SWF file. For more information, see Author (developer) controls.
To access a Bitmap object that was loaded by a Loader object, a cross-domain policy file must exist on the origin server of the image file, and that cross-domain policy file must grant permission to the domain of the SWF file trying to access the Bitmap object (see Website controls (cross-domain policy files)).
The LoaderInfo object that corresponds to a loaded file (and to the Loader object) includes the following three properties, which define the relationship between the loaded object and the Loader object: childAllowsParent, parentAllowsChild, and sameDomain.
Event security
Events related to the display list have security access limitations, based on the sandbox of the display object that is dispatching the event. An event in the display list has bubbling and capture phases (described in Handling events). During the bubbling and capture phases, an event migrates from the source display object through parent display objects in the display list. If a parent object is in a different security sandbox than the source display object, the capture and bubble phase stops below that parent object, unless there is mutual trust between the owner of the parent object and the owner of the source object. This mutual trust can be achieved by the following:
The SWF file that owns the parent object must call the Security.allowDomain() method to trust the domain of the SWF file that owns the source object.
The SWF file that owns the source object must call the Security.allowDomain() method to trust the domain of the SWF file that owns the parent object.
The LoaderInfo object that corresponds to a loaded file (and to the Loader object) includes the following two properties, which define the relationship between the loaded object and the Loader object: childAllowsParent and parentAllowsChild.
For events that are dispatched from objects other than display objects, there are no security checks or security-related implications.
flex Loading content
A SWF file can load the following types of content:
SWF files
Images
Sound
Video
Subtopics
Loading SWF files and images
Loading sound and videos
Loading SWF files and images using the tag in a text field
Content delivered using RTMP servers
Loading SWF files and images
You use the Loader class to load SWF files and images (JPG, GIF, or PNG files). Any SWF file, other than one in the local-with-filesystem sandbox, can load SWF files and images from any network domain. Only SWF files in local sandboxes can load SWF files and images from the local file system. However, files in the local-with-networking sandbox can only load local SWF files that are in the local-trusted or local-with-networking sandbox. SWF files in the local-with-networking sandbox load local content other than SWF files (such as images), however they cannot access data in the loaded content.
When loading a SWF file from a non-trusted source (such as a domain other than that of the Loader object's root SWF file), you may want to define a mask for the Loader object, to prevent the loaded content (which is a child of the Loader object) from drawing to portions of the Stage outside of that mask, as in the following code:
import flash.display.*;
import flash.net.URLRequest;
var rect:Shape = new Shape();
rect.graphics.beginFill(0xFFFFFF);
rect.graphics.drawRect(0, 0, 100, 100);
addChild(rect);
var ldr:Loader = new Loader();
ldr.mask = rect;
var url:String = "http://www.unknown.example.com/content.swf";
var urlReq:URLRequest = new URLRequest(url);
ldr.load(urlReq);
addChild(ldr);
When you call the load() method of the Loader object, you can specify a context parameter, which is a LoaderContext object. The LoaderContext class includes three properties that let you define the context of how the loaded content can be used:
checkPolicyFile: Use this property only when loading an image file (not a SWF file). Specify this for an image file from a domain other than that of the file containing the Loader object. If you set this property to true, the Loader checks the origin server for a cross-domain policy file (see Website controls (cross-domain policy files)). If the server grants permission to the Loader domain, ActionScript from SWF files in the Loader domain can access data in the loaded image. In other words, you can use the Loader.content property to obtain a reference to the Bitmap object that represents the loaded image, or the BitmapData.draw() method to access pixels from the loaded image.
securityDomain: Use this property only when loading a SWF file (not an image). Specify this for a SWF file from a domain other than that of the file containing the Loader object. Only two values are currently supported for the securityDomain property: null (the default) and SecurityDomain.currentDomain. If you specify SecurityDomain.currentDomain, this requests that the loaded SWF file be imported to the sandbox of the loading SWF file, meaning that it operates as though it had been loaded from the loading SWF file's own server. This is only permitted if a cross-domain policy file is found on the loaded SWF file's server, allowing access by the loading SWF file's domain. If the required policy file is found, the loader and loadee can freely script each other once the load begins, since they are in the same sandbox. Note that sandbox importing can mostly be replaced by performing an ordinary load and then having the loaded SWF file call the Security.allowDomain() method. This latter method may be easier to use, since the loaded SWF file will then be in its own natural sandbox, and thus able to access resources on its own actual server.
applicationDomain: Use this property only when loading a SWF file written in ActionScript 3.0 (not an image or a SWF file written in ActionScript 1.0 or 2.0). When loading the file, you can specify that the file be placed into a particular application domain, rather than the default of being placed in a new application domain that is a child of the loading SWF file's application domain. Note that application domains are subunits of security domains, and thus you can specify a target application domain only if the SWF file that you are loading is from your own security domain, either because it is from your own server, or because you have successfully imported it into your security domain using the securityDomain property. If you specify an application domain but the loaded SWF file is part of a different security domain, the domain you specify in applicationDomain is ignored. For more information, see Using the ApplicationDomain class.
For details, see Specifying loading context.
An important property of a Loader object is the contentLoaderInfo property, which is a LoaderInfo object. Unlike most other objects, a LoaderInfo object is shared between the loading SWF file and the loaded content, and it is always accessible to both parties. When the loaded content is a SWF file, it can access the LoaderInfo object through the DisplayObject.loaderInfo property. LoaderInfo objects include information such as load progress, the URLs of loader and loadee, the trust relationship between loader and loadee, and other information. For more information, see Monitoring loading progress.
Loading sound and videos
All SWF files, other than those in the local-with-filesystem sandbox, are allowed to load sound and video from network origins, using the Sound.load(), NetConnection.connect(), and NetStream.play() methods.
Only local SWF files can load media from the local file system. Only SWF files in the local-with-filesystem sandbox or the local-trusted sandbox can access data in these loaded files.
There are other restrictions on accessing data from loaded media. For details, see Accessing loaded media as data.
Loading SWF files and images using the tag in a text field
You can load SWF files and bitmaps into a text field by using the tag, as in the following code:
You can access content loaded this way by using the getImageReference() method of the TextField instance, as in the following code:
var loadedObject:DisplayObject = myTextField.getImageReference('instanceName');
Note, however, that SWF files and images loaded in this way are put in the sandbox that corresponds to their origin.
When you load an image file using an tag in a text field, access to the data in the image may be permitted by a cross-domain policy file. You can check for a policy file by adding a checkPolicyFile attribute to the
tag, as in the following code:
When you load a SWF using an tag in a text field, you can permit access to that SWF file's data through a call to the Security.allowDomain() method.
When you use an tag in a text field to load an external file (as opposed to using a Bitmap class embedded within your SWF), a Loader object is automatically created as a child of the TextField object, and the external file is loaded into that Loader just as if you had used a Loader object in ActionScript to load the file. In this case, the getImageReference() method returns the Loader that was automatically created. No security check is needed to access this Loader object because it is in the same security sandbox as the calling code.
However, when you refer to the content property of the Loader object to access the loaded media, security rules apply. If the content is an image, you need to implement a cross-domain policy file, and if the content is a SWF file, you need to have the code in the SWF file call the allowDomain() method.
Content delivered using RTMP servers
Flash Media Server uses the Real-Time Media Protocol (RTMP) to serve data, audio, and video. A SWF file loads this media by using the connect() method of the NetConnection class, passing an RTMP URL as the parameter. Flash Media Server can restrict connections and prevent content from downloading, based on the domain of the requesting file. For details, see the Flash Media Server documentation.
For media loaded from RTMP sources, you cannot use the BitmapData.draw() and SoundMixer.computeSpectrum() methods to extract run-time graphics and sound data.
Full-screen mode security
Flash Player 9.0.27.0 and later support full-screen mode, in which Flash content can fill the entire screen. To enter full-screen mode, the displayState property of the Stage is set to the StageDisplayState.FULL_SCREEN constant. For more information, see Working with full-screen mode.
For SWF files running in a browser, there are some security considerations.
To enable full-screen mode, in the
An HTML page may also use a script to generate SWF-embedding tags. You must alter the script so that it inserts the proper allowFullScreen settings. HTML pages generated by Flash and Flex Builder use the AC_FL_RunContent() function to embed references to SWF files, and you need to add the allowFullScreen parameter settings, as in the following:
AC_FL_RunContent( ... "allowFullScreen", "true", ...)
The ActionScript that initiates full-screen mode can be called only in response to a mouse event or keyboard event. If it is called in other situations, Flash Player throws an exception.
Users cannot enter text in text input fields while in full-screen mode. All keyboard input and keyboard-related ActionScript is disabled while in full-screen mode, with the exception of the keyboard shortcuts (such as pressing the Esc key) that return the application to normal mode.
A message appears when the content enters full-screen mode, instructing the user how to exit and return to normal mode. The message appears for a few seconds and then fades out.
Calling the displayState property of a Stage object throws an exception for any caller that is not in the same security sandbox as the Stage owner (the main SWF file). For more information, see Stage security.
Administrators can disable full-screen mode for SWF files running in browsers by setting FullScreenDisable = 1 in the mms.cfg file. For details, see Administrative user controls.
In a browser, a SWF file must be contained in an HTML page to allow full-screen mode.
Full-screen mode is always permitted in the stand-alone player or in a projector file.
Flex Player Restricting networking APIs
You can control a SWF file's access to network functionality by setting the allowNetworking parameter in the and tags in the HTML page that contains the SWF content.
Possible values of allowNetworking are:
- "all" (the default)--All networking APIs are permitted in the SWF.
- "internal"--The SWF file may not call browser navigation or browser interaction APIs, listed later in this section, but it may call any other networking APIs.
- "none"--The SWF file may not call browser navigation or browser interaction APIs, listed later in this section, and it cannot use any SWF-to-SWF communication APIs, also listed later.
Calling a prevented API throws a SecurityError exception.
To set the allowNetworking parameter, in the and tags in the HTML page that contains a reference the SWF file, add the allowNetworking parameter and set its value, as shown in the following example:
codebase="http://fpdownload.macromedia.com/pub/shockwave/cabs/flash/swflash.cab#version=9,0,18,0"
width="600" height="400" id="test" align="middle">
width="600" height="400"
name="test" align="middle" type="application/x-shockwave-flash"
pluginspage="http://www.macromedia.com/go/getflashplayer" />
An HTML page may also use a script to generate SWF-embedding tags. You need to alter the script so that it inserts the proper allowNetworking settings. HTML pages generated by Flash and Adobe Flex Builder use the AC_FL_RunContent() function to embed references to SWF files, and you need to add the allowNetworking parameter settings to the script, as in the following:
AC_FL_RunContent( ... "allowNetworking", "none", ...)
The following APIs are prevented when allowNetworking is set to "internal":
- navigateToURL()
- fscommand()
- ExternalInterface.call()
An addition to those APIs on the previous list, the following APIs are also prevented when allowNetworking is set to "none":
- sendToURL()
- FileReference.download()
- FileReference.upload()
- Loader.load()
- LocalConnection.connect()
- LocalConnection.send()
- NetConnection.connect()
- NetStream.play()
- Security.loadPolicyFile()
- SharedObject.getLocal()
- SharedObject.getRemote()
- Socket.connect()
- Sound.load()
- URLLoader.load()
- URLStream.load()
- XMLSocket.connect()
Even if the selected allowNetworking setting permits a SWF file to use a networking API, there may be other restrictions based on security sandbox limitations, as described in this chapter.
When allowNetworking is set to "none", you cannot reference external media in an tag in the htmlText property of a TextField object (a SecurityError exception is thrown).
Flex Security sandboxes
Client computers can obtain individual SWF files from a number of sources, such as from external web sites or from a local file system. Flash Player individually assigns SWF files and other resources, such as shared objects, bitmaps, sounds, videos, and data files, to security sandboxes based on their origin when they are loaded into Flash Player. The following sections describe the rules, enforced by Flash Player, that govern what a SWF file within a given sandbox can access.
For more information on security sandboxes, see the Flash Player 9 Security white paper.
Remote sandboxes
Flash Player classifies assets (including SWF files) from the Internet in separate sandboxes that correspond to their website origin domains. By default, these files are authorized to access any resources from their own server. Remote SWF files can be allowed to access additional data from other domains by explicit website and author permissions, such as cross-domain policy files and the Security.allowDomain() method. For details, see Website controls (cross-domain policy files) and Author (developer) controls.
Remote SWF files cannot load any local files or resources.
For more information, see the Flash Player 9 Security white paper.
Local sandboxes
Local file describes any file that is referenced by using the file: protocol or a Universal Naming Convention (UNC) path. Local SWF files are placed into one of three local sandboxes:
- The local-with-filesystem sandbox--For security purposes, Flash Player places all local SWF files and assets in the local-with-file-system sandbox, by default. From this sandbox, SWF files can read local files (by using the URLLoader class, for example), but they cannot communicate with the network in any way. This assures the user that local data cannot be leaked out to the network or otherwise inappropriately shared.
- The local-with-networking sandbox--When compiling a SWF file, you can specify that it has network access when run as a local file (see Setting the sandbox type of local SWF files).These files are placed in the local-with-networking sandbox. SWF files that are assigned to the local-with-networking sandbox forfeit their local file access. In return, the SWF files are allowed to access data from the network. However, a local-with-networking SWF file is still not allowed to read any network-derived data unless permissions are present for that action, through a cross-domain policy file or a call to the Security.allowDomain() method. In order to grant such permission, a cross-domain policy file must grant permission to all domains by using
or by using Security.allowDomain("*"). For more information, see Website controls (cross-domain policy files) and Author (developer) controls. - The local-trusted sandbox--Local SWF files that are registered as trusted (by users or by installer programs) are placed in the local-trusted sandbox. System administrators and users also have the ability to reassign (move) a local SWF file to or from the local-trusted sandbox based on security considerations (see Administrative user controls and User controls). SWF files that are assigned to the local-trusted sandbox can interact with any other SWF files and can load data from anywhere (remote or local).
Communication between the local-with-networking and local-with-filesystem sandboxes, as well as communication between the local-with-filesystem and remote sandboxes, is strictly forbidden. Permission to allow such communication cannot be granted by a Flash application or by a user or administrator.
Scripting in either direction between local HTML files and local SWF files--for example, using the ExternalInterface class--requires that both the HTML file and SWF file involved be in the local-trusted sandbox. This is because the local security models for browsers differ from the Flash Player local security model.
SWF files in the local-with-networking sandbox cannot load SWF files in the local-with-filesystem sandbox. SWF files in the local-with-filesystem sandbox cannot load SWF files in the local-with-networking sandbox.
Setting the sandbox type of local SWF files
You can configure a SWF file for the local-with-filesystem sandbox or the local-with-networking sandbox by setting the use-network flag in the Adobe Flex compiler. For more information, see About the application compiler options in Building and Developing Flex Applications.
An end user or the administrator of a computer can specify that a local SWF file is trusted, allowing it to load data from all domains, both local and network. This is specified in the Global Flash Player Trust and User Flash Player Trust directories. For more information, see Administrative user controls and User controls.
For more information on local sandboxes, see Local sandboxes.
The Security.sandboxType property
An author of a SWF file can use the read-only static Security.sandboxType property to determine the type of sandbox to which Flash Player has assigned the SWF file. The Security class includes constants that represent possible values of the Security.sandboxType property, as follows:
- Security.REMOTE--The SWF file is from an Internet URL, and operates under domain-based sandbox rules.
- Security.LOCAL_WITH_FILE--The SWF file is a local file, but it has not been trusted by the user and was not published with a networking designation. The SWF file can read from local data sources but cannot communicate with the Internet.
- Security.LOCAL_WITH_NETWORK--The SWF file is a local file and has not been trusted by the user, but it was published with a networking designation. The SWF can communicate with the Internet but cannot read from local data sources.
- Security.LOCAL_TRUSTED--The SWF file is a local file and has been trusted by the user, using either the Settings Manager or a Flash Player trust configuration file. The SWF file can both read from local data sources and communicate with the Internet.
Flex player Overview of permission controls
The Flash Player client run-time security model has been designed around resources, which are objects such as SWF files, local data, and Internet URLs. Stakeholders are the parties who own or use those resources. Stakeholders can exercise controls (security settings) over their own resources, and each resource has four stakeholders. Flash Player strictly enforces a hierarchy of authority for these controls, as the following illustration shows:
This means, for instance, that if an administrator restricts access to a resource, no other stakeholders can override that restriction.
Administrator, user, and website controls are detailed in the following sections. Author (developer) settings are described in the rest of this chapter.
Administrative user controls
An administrative user of a computer (a user who has logged in with administrative rights) can apply Flash Player security settings that affect all users of the computer. In a nonenterprise environment, such as on a home computer, there is usually one user who also has administrative access. Even in an enterprise environment, individual users may have administrative rights to the computer.
There are two types of administrative user controls:
- The mms.cfg file
- The Global Flash Player Trust directory
On Mac OS X systems, the mms.cfg file is located at /Library/Application Support/Macromedia/mms.cfg. On Microsoft Windows systems, the file is located in the Macromedia Flash Player folder in the system directory (for example, C:\windows\system32\macromed\flash\mms.cfg on a default Windows XP or Windows Vista installation).
When Flash Player starts, it reads its security settings from this file, and uses them to limit functionality.
The mms.cfg file includes settings that the administrator uses to perform the following tasks:
- Data loading--Restrict the reading of local SWF files, disable file downloading and uploading, and set the storage limit for persistent shared objects.
- Privacy controls--Disable microphone and camera access, prevent SWF files from playing windowless content, and prevent SWF files in a domain that does not match the URL displayed in a browser window from accessing persistent shared objects.
- Flash Player updates--Set the interval for checking for an updated version of Flash Player, specify the URL to check for Flash Player update information, specify the URL from which to download updated versions of Flash Player, and disable automatic updates of Flash Player entirely.
- Legacy file support--Specify whether older-version SWF files should be placed in the local-trusted sandbox.
- Local file security--Specify whether local files can be placed in the local-trusted sandbox.
- Full-screen mode--Disable full-screen mode.
A SWF file can access some information on capabilities that have been disabled by calling the Capabilities.avHardwareDisable and Capabilities.localFileReadDisable properties. However, most of the settings in the mms.cfg file cannot be queried from ActionScript.
To enforce application-independent security and privacy policies for a computer, the mms.cfg file should be modified only by system administrators. The mms.cfg file is not for use by application installers. While an installer running with administrative privileges could modify the contents of the mms.cfg file, Adobe considers such usage a violation of the user's trust and urges creators of installers never to modify the mms.cfg file.
The Global Flash Player Trust directory
Administrative users and installer applications can register specified local SWF files as trusted. These SWF files are assigned to the local-trusted sandbox. They can interact with any other SWF files, and they can load data from anywhere, remote or local. Files are designated as trusted in the Global Flash Player Trust directory, which is in the same directory as the mms.cfg file, in the following locations (locations are specific to the current user):
- Windows: system\Macromed\Flash\FlashPlayerTrust
(for example, C:\windows\system32\Macromed\Flash\FlashPlayerTrust)
- Mac: app support/Macromedia/FlashPlayerTrust
(for example, /Library/Application Support/Macromedia/FlashPlayerTrust)
The Flash Player Trust directory can contain any number of text files, each of which lists trusted paths, with one path per line. Each path can be an individual SWF file, HTML file, or directory. Comment lines begin with the # symbol. For example, a Flash Player trust configuration file containing the following text grants trusted status to all files in the specified directory and all subdirectories:
# Trust files in the following directories:
C:\Documents and Settings\All Users\Documents\SampleApp
The paths listed in a trust configuration file should always be local paths or SMB network paths. Any HTTP path in a trust configuration file is ignored; only local files can be trusted.
To avoid conflicts, give each trust configuration file a filename corresponding to the installing application, and use a .cfg file extension.
As a developer distributing a locally run SWF file through an installer application, you can have the installer application add a configuration file to the Global Flash Player Trust directory, granting full privileges to the file that you are distributing. The installer application must be run by a user with administrative rights. Unlike the mms.cfg file, the Global Flash Player Trust directory is included for the purpose of installer applications granting trust permissions. Both administrative users and installer applications can designate trusted local applications using the Global Flash Player Trust directory.
There are also Flash Player Trust directories for individual users (see the next section, User controls).
User controls
Flash Player provides three different user-level mechanisms for setting permissions: the Settings UI, the Settings Manager, and the User Flash Player Trust directory.
The Settings UI and Settings Manager
The Settings UI is a quick, interactive mechanism for configuring the settings for a specific domain. The Settings Manager presents a more detailed interface and provides the ability to make global changes that affect permissions for many or all domains. Additionally, when a new permission is requested by a SWF file, requiring run-time decisions concerning security or privacy, dialog boxes are displayed in which users can adjust some Flash Player settings.
The Settings Manager and Settings UI provide the following security-related options:
- Camera and microphone settings--The user can control Flash Player access to the camera and microphone on the computer. The user can allow or deny access for all sites or for specific sites. If the user does not specify a setting for all sites or a specific site, a dialog box is displayed when a SWF file attempts to access the camera or microphone, letting the user choose whether or not to allow the SWF file to access the device. The user can also specify the camera or microphone to use, and can set the sensitivity of the microphone.
- Shared object storage settings--The user can select the amount of disk space that a domain can use to store persistent shared objects. The user can make these settings for any numbers of specific domains, and can specify the default setting for new domains. The default limit is 100 KB of disk space. For more information on persistent shared objects, see the SharedObject class in the ActionScript 3.0 Language and Components Reference.
For details on the Settings Manager, see www.adobe.com/go/settingsmanager.
The User Flash Player Trust directory
Users and installer applications can register specified local SWF files as trusted. These SWF files are assigned to the local-trusted sandbox. They can interact with any other SWF files, and they can load data from anywhere, remote or local. A user designates a file as trusted in the User Flash Player Trust directory, which is in same directory as the Flash shared object storage area, in the following locations (locations are specific to the current user):
- Windows: app data\Macromedia\Flash Player\#Security\FlashPlayerTrust
(for example, C:\Documents and Settings\JohnD\Application Data\Macromedia\Flash Player\#Security\FlashPlayerTrust on Windows XP or C:\Users\JohnD\AppData\Roaming\Macromedia\Flash Player\#Security\FlashPlayerTrust on Windows Vista)
- Mac: app data/Macromedia/Flash Player/#Security/FlashPlayerTrust
(for example, /Users/JohnD/Library/Preferences/Macromedia/Flash Player/#Security/FlashPlayerTrust)
These settings affect only the current user, not other users who log in to the computer. If a user without administrative rights installs an application in their own portion of the system, the User Flash Player Trust directory lets the installer register the application as trusted for that user.
As a developer distributing a locally run SWF file by way of an installer application, you can have the installer application add a configuration file to the User Flash Player Trust directory, granting full privileges to the file that you are distributing. Even in this situation, the User Flash Player Trust directory file is considered a user control, because a user action (installation) initiates it.
There is also a Global Flash Player Trust directory, used by the administrative user or installers to register an application for all users of a computer (see Administrative user controls).
Website controls (cross-domain policy files)
To make data from a web server available to SWF files from other domains, you can create a cross-domain policy file on your server. A cross-domain policy file is an XML file that provides a way for the server to indicate that its data and documents are available to SWF files served from certain domains or from all domains. Any SWF file that is served from a domain specified by the server's policy file is permitted to access data or assets from that server.
Cross-domain policy files affect access to a number of assets, including the following:
- Data in bitmaps, sounds, and videos
- Loading XML and text files
- Access to socket and XML socket connections
- Importing SWF files from other security domains into the security domain of the loading SWF file
Full details are provided in the rest of this chapter.
The following example shows a policy file that permits access to SWF files that originate from *.example.com, www.friendOfExample.com and 192.0.34.166:
When a SWF file attempts to access data from another domain, Flash Player automatically attempts to load a policy file from that domain. If the domain of the SWF file that is attempting to access the data is included in the policy file, the data is automatically accessible.
By default, policy files must be named crossdomain.xml and must reside in the root directory of the server. However, a SWF file can check for a different name or in a different directory location by calling the Security.loadPolicyFile() method. A cross-domain policy file applies only to the directory from which it is loaded and to its child directories. So a policy file in the root directory applies to the whole server, but a policy file loaded from an arbitrary subdirectory applies only to that directory and its subdirectories.
A policy file affects access only to the particular server on which it resides. For example, a policy file located at https://www.adobe.com:8080/crossdomain.xml will apply only to data- loading calls made to www.adobe.com over HTTPS at port 8080.
A cross-domain policy file contains a single
If you specify an IP address, access is granted only to SWF files loaded from that IP address using IP syntax (for example, http://65.57.83.12/flashmovie.swf), not those loaded using domain-name syntax. Flash Player does not perform DNS resolution.
You can permit access to documents originating from any domain, as shown in the following example:
Each
Setting the secure attribute to false could compromise the security offered by HTTPS. In particular, setting this attribute to false opens secure content to snooping and spoofing attacks. Adobe strongly recommends that you not set the secure attribute to false.
If data to be loaded is on a HTTPS server, but the SWF file loading it is on an HTTP server, Adobe recommends that you move the loading SWF file to an HTTPS server so that you can keep all copies of your secure data under the protection of HTTPS. However, if you decide that you must keep the loading SWF file on an HTTP server, add the secure="false" attribute to the
A policy file that contains no
ActionScript objects instantiate two different kinds of server connections: document-based server connections and socket connections. ActionScript objects like Loader, Sound, URLLoader, and URLStream instantiate document-based server connections, and these each load a file from a URL. ActionScript Socket and XMLSocket objects make socket connections, which operate with streaming data, not loaded documents. Flash Player supports two kinds of policy files: document-based policy files and socket policy files. Document-based connections require document-based policy files, while socket connections require socket policy files.
Flash Player requires that a policy file be transmitted using the same kind of protocol that the attempted connection wishes to use. For example, when you place a policy file on your HTTP server, SWF files from other domains are allowed to load data from it as an HTTP server. However, by not providing a socket policy file at the same server, you are forbidding SWF files from other domains to connect to the server at the socket level. The means by which a socket policy file is retrieved must match the means of connecting.
A policy file served by a socket server has the same syntax as any other policy file, except that it must also specify the ports to which it grants access. When a policy file comes from a port number that is less than 1024, it may grant access to any ports; when a policy file comes from port 1024 or higher, it may only grant access to ports 1024 and higher. The allowed ports are specified in a to-ports attribute in the
Here is an example XMLSocket policy file:
When policy files were first introduced in Flash Player 6, there was no support for socket policy files. Connections to socket servers were authorized by a policy file from the default location of the cross-domain policy file on an HTTP server on port 80 of the same host as the socket server. To make it possible to preserve existing server arrangements, Flash Player 9 still supports this capability. However, Flash Player's default is now to retrieve a socket policy file on the same port as the socket connection. If you wish to use an HTTP-based policy file to authorize a socket connection, you must explicitly request the HTTP policy file using code such as the following:
Security.loadPolicyFile("http://socketServerHost.com/crossdomain.xml")
In addition, in order to authorize socket connections, an HTTP policy file must come only from the default location of the cross-domain policy file, and not from any other HTTP location. A policy file obtained from an HTTP server implicitly authorizes socket access to all ports 1024 and above; any to-ports attributes in an HTTP policy file are ignored.
For more information on socket policy files, see Connecting to sockets.
Loading data from a server or connecting to a socket is an asynchronous operation, and Flash Player simply waits for the cross-domain policy file to finish downloading before it begins the main operation. However, extracting pixel data from images or extracting sample data from sounds is a synchronous operation--the cross-domain policy file must load before you can extract data. When you load the media, you need to specify that it check for a cross-domain policy file:
- When using the Loader.load() method, set the checkPolicyFile property of the context parameter, which is a LoaderContext object.
- When embedding an image in a text field using the
tag, set the checkPolicyFile attribute of the
tag to "true", as in the following:
. - When using the Sound.load() method, set the checkPolicyFile property of the context parameter, which is a SoundLoaderContext object.
- When using the NetStream class, set the checkPolicyFile property of the NetStream object.
When you set one of these parameters, Flash Player first checks for any policy files that it already has downloaded for that domain. Then it considers any pending calls to the Security.loadPolicyFile() method to see if they are in scope, and waits for those if they are. Then it looks for the cross-domain policy file in the default location on the server.
Author (developer) controls
The main ActionScript API used to grant security privileges is the Security.allowDomain() method, which grant privileges to SWF files in the domains that you specify. In the following example, a SWF file grants access to SWF files served from the www.example.com domain:
Security.allowDomain("www.example.com")
This method grants permissions for the following:
- Cross-scripting between SWF files (see Cross-scripting)
- Display list access (see Traversing the display list)
- Event detection (see Event security)
- Full access to properties and methods of the Stage object (see Stage security)
The primary purpose of calling the Security.allowDomain() method is to grant permission for SWF files in an outside domain to script the SWF file calling the Security.allowDomain() method. For more information, see Cross-scripting.
Specifying an IP address as a parameter to the Security.allowDomain() method does not permit access by all parties that originate at the specified IP address. Instead, it permits access only by a party that contains the specified IP address as its URL, rather than a domain name that maps to that IP address. For example, if the domain name www.example.com maps to the IP address 192.0.34.166, a call to Security.allowDomain("192.0.34.166") does not grant access to www.example.com.
You can pass the "*" wildcard to the Security.allowDomain() method to allow access from all domains. Because it grants permission for SWF files from all domains to script the calling SWF file, use the "*" wildcard with care.
ActionScript includes a second permission API, called Security.allowInsecureDomain(). This method does the same thing as the Security.allowDomain() method, except that, when called from a SWF file served by a secure HTTPS connection, it additionally permits access to the calling SWF file by other SWF files that are served from an insecure protocol, such as HTTP. However, it is not a good security practice to allow scripting between files from a secure protocol (HTTPS) and those from insecure protocols (such as HTTP); doing so can open secure content to snooping and spoofing attacks. Here is how such attacks can work: since the Security.allowInsecureDomain() method allows access to your secure HTTPS data by SWF files served over HTTP connections, an attacker interposed between your HTTP server and your users could replace your HTTP SWF file with one of their own, which can then access your HTTPS data.
Another important security-related method is the Security.loadPolicyFile() method, which causes Flash Player to check for a cross-domain policy file at a nonstandard location. For more information, see Website controls (cross-domain policy files).
Flash Player security overview
Much of Flash Player security is based on the domain of origin for loaded SWF files, media, and other assets. A SWF file from a specific Internet domain, such as www.example.com, can always access all data from that domain. These assets are put in the same security grouping, known as a security sandbox. (For more information, see Security sandboxes.)
For example, a SWF file can load SWF files, bitmaps, audio, text files, and any other asset from its own domain. Also, cross-scripting between two SWF files from the same domain is always permitted, as long as both files are written using ActionScript 3.0. Cross-scripting is the ability of one SWF file to use ActionScript to access the properties, methods, and objects in another SWF file. Cross-scripting is not supported between SWF files written using ActionScript 3.0 and those using previous versions of ActionScript; however, these files can communicate by using the LocalConnection class. For more information, see Cross-scripting.
The following basic security rules always apply by default:
- Resources in the same security sandbox can always access each other.
- SWF files in a remote sandbox can never access local files and data.
Flash Player considers the following to be individual domains, and sets up individual security sandboxes for each:
- http://example.com
- http://www.example.com
- http://store.example.com
- https://www.example.com
- http://192.0.34.166
Even if a named domain, such as http://example.com, maps to a specific IP address, such as http://192.0.34.166, Flash Player sets up separate security sandboxes for both.
There are two basic methods that a developer can use to grant a SWF file access to assets from sandboxes other than that of the SWF file:
- The Security.allowDomain() method (see Author (developer) controls)
- The cross-domain policy file (see Website controls (cross-domain policy files))
The ability of a SWF file to cross-script ActionScript 3.0 SWF files from other domains and to load data from other domains is prohibited by default. It can be granted with a call to the Security.allowDomain() method in the loaded SWF file. For details, see Cross-scripting.
In the Flash Player security model, there is a distinction between loading content and accessing or loading data:
- Loading content--Content is defined as media, including visual media Flash Player can display, audio, video, or a SWF file that includes displayed media. Data is defined as something that is accessible only to ActionScript code. You can load content using classes such as the Loader, Sound, and NetStream classes.
- Accessing content as data or loading data--You can access data in two ways: by extracting data from loaded media content or by directly loading data from an external file (such as an XML file). You can extract data from loaded media by using Bitmap objects, the BitmapData.draw() method, the Sound.id3 property, or the SoundMixer.computeSpectrum() method. You can load data using classes such as the URLStream, URLLoader, Socket, and XMLSocket classes.
The Flash Player security model defines different rules for loading content and accessing data. In general, there are fewer restrictions on loading content than on accessing data.
In general, content (SWF files, bitmaps, mp3 files, and videos) can be loaded from anywhere, but if the content is from a domain other than that of the loading SWF file, it will be partitioned in a separate security sandbox.
There are a few barriers to loading content:
- By default, local SWF files (those loaded from a non-network address, such as a user's hard drive) are classified in the local-with-filesystem sandbox. These files cannot load content from the network. For more information, see Local sandboxes.
- Real-Time Messaging Protocol (RTMP) servers can limit access to content. For more information, see Content delivered using RTMP servers.
If the loaded media is an image, audio, or video, its data, such as pixel data and sound data, cannot be accessed by a SWF file outside its security sandbox, unless the domain of that SWF file has been included in a cross-domain policy file at the origin domain of the media. For details, see Accessing loaded media as data.
Other forms of loaded data include text or XML files, which are loaded with a URLLoader object. Again in this case, to access any data from another security sandbox, permission must be granted by means of a cross-domain policy file at the origin domain. For details, see Using URLLoader and URLStream.
flex Flash Player security
Security is a key concern of Adobe, users, website owners, and content developers. For this reason, Adobe®Flash™ Player 9 includes a set of security rules and controls to safeguard the user, website owner, and content developer. This chapter discusses how to work with the Flash Player security model when you are developing applications. In this chapter, all SWF files discussed are assumed to be published with ActionScript™ 3.0 (and thus running in Flash Player 9 or later), unless otherwise noted. For information about Adobe AIR security issues, see AIR Security in Developing Adobe AIR Applications with Flash CS3 Professional or Developing AIR Applications with Adobe Flex 3
This chapter is intended as an overview of security; it does not try to comprehensively explain all implementation details, usage scenarios, or ramifications for using certain APIs. For a more detailed discussion of Flash Player Security concepts, see the Flash Player 9 Security white paper, at www.adobe.com/go/fp9_0_security.
flex Example: RuntimeAssetsExplorer
The Export for ActionScript functionality can be especially advantageous for libraries that may be useful across more than one project. If Flash Player or AIR executes a SWF file, symbols that have been exported to ActionScript are available to any SWF file within the same security sandbox as the SWF that loads it. In this way, a single Flash document can generate a SWF file that is designated for the sole purpose of holding graphical assets. This technique is particularly useful for larger projects where designers working on visual assets can work in parallel with developers who create a "wrapper" SWF file that then loads the graphical assets SWF file at run time. You can use this method to maintain a series of versioned files where graphical assets are not dependent upon the progress of programming development.
The RuntimeAssetsExplorer application loads any SWF file that is a subclass of RuntimeAsset and allows you to browse the available assets of that SWF file. The example illustrates the following:
Loading an external SWF file using Loader.load()
Dynamic creation of a library symbol exported for ActionScript
ActionScript control of MovieClip playback
Before beginning, note that each of the SWF files to run in Flash Player must be located in the same security sandbox. For more information, see Security sandboxes.
To get the application files for this sample, see www.adobe.com/go/learn_programmingAS3samples_flash. The RuntimeAssetsExplorer application files can be found in the folder Samples/RuntimeAssetsExplorer. The application consists of the following files:
File
Description
RuntimeAssetsExample.mxml
or
RuntimeAssetsExample.fla
The user interface for the application for Flex (MXML) or Flash (FLA).
GeometricAssets.as
An example class that implements the RuntimeAsset interface.
GeometricAssets.fla
A FLA file linked to the GeometricAssets class (the document class of the FLA) containing symbols that are exported for ActionScript.
com/example/programmingas3/runtimeassetsexplorer/RuntimeLibrary.as
An interface that defines the required methods expected of all run-time asset SWF files that will be loaded into the explorer container.
com/example/programmingas3/runtimeassetsexplorer/AnimatingBox.as
The class of the library symbol in the shape of a rotating box.
com/example/programmingas3/runtimeassetsexplorer/AnimatingStar.as
The class of the library symbol in the shape of a rotating star.
Subtopics
Establishing a run-time library interface
Creating the asset library SWF file
Loading the library into another SWF file
Establishing a run-time library interface
In order for the explorer to properly interact with a SWF library, the structure of the run-time asset libraries must be formalized. We will accomplish this by creating an interface, which is similar to a class in that it's a blueprint of methods that demarcate an expected structure, but unlike a class it includes no method bodies. The interface provides a way for both the run-time library and the explorer to communicate to one another. Each SWF of run-time assets that is loaded in our browser will implement this interface. For more information about interfaces and how they can be useful, see Interfaces.
The RuntimeLibrary interface will be very simple--we merely require a function that can provide the explorer with an array of classpaths for the symbols to be exported and available in the run-time library. To this end, the interface has a single method: getAssets().
package com.example.programmingas3.runtimeassetexplorer
{
public interface RuntimeLibrary
{
function getAssets():Array;
}
}
Creating the asset library SWF file
By defining the RuntimeLibrary interface, it's possible to create multiple asset library SWF files that can be loaded into another SWF file. Making an individual SWF library of assets involves four tasks:
Creating a class for the asset library SWF file
Creating classes for individual assets contained in the library
Creating the actual graphic assets
Associating graphic elements with classes and publishing the library SWF
Creating a class to implement the RuntimeLibrary interface
Next, we'll create the GeometricAssets class that will implement the RuntimeLibrary interface. This will be the document class of the FLA. The code for this class is very similar to the RuntimeLibrary interface--the difference between them is that in the class definition the getAssets() method has a method body.
package
{
import flash.display.Sprite;
import com.example.programmingas3.runtimeassetexplorer.RuntimeLibrary;
public class GeometricAssets extends Sprite implements RuntimeLibrary
{
public function GeometricAssets() {
}
public function getAssets():Array {
return [ "com.example.programmingas3.runtimeassetexplorer.AnimatingBox",
"com.example.programmingas3.runtimeassetexplorer.AnimatingStar" ];
}
}
}
If we were to create a second run-time library, we could create another FLA based upon another class (for example, AnimationAssets) that provides its own getAssets() implementation.
Creating classes for each MovieClip asset
For this example, we'll merely extend the MovieClip class without adding any functionality to the custom assets. The following code for AnimatingStar is analogous to that of AnimatingBox:
package com.example.programmingas3.runtimeassetexplorer
{
import flash.display.MovieClip;
public class AnimatingStar extends MovieClip
{
public function AnimatingStar() {
}
}
}
Publishing the library
We'll now connect the MovieClip-based assets to the new class by creating a new FLA and entering GeometricAssets into the Document Class field of the Property inspector. For the purposes of this example, we'll create two very basic shapes that use a timeline tween to make one clockwise rotation over 360 frames. Both the animatingBox and animatingStar symbols are set to Export for ActionScript and have the Class field set to the respective classpaths specified in the getAssets() implementation. The default base class of flash.display.MovieClip remains, as we want to subclass the standard MovieClip methods.
After setting up your symbol's export settings, publish the FLA. You now have your first run-time library. This SWF file could be loaded into another AVM2 SWF file and the AnimatingBox and AnimatingStar symbols would be available to the new SWF file.
Loading the library into another SWF file
The last functional piece to deal with is the user interface for the asset explorer. In this example, the path to the run-time library is hard-coded as a variable named ASSETS_PATH. Alternatively, you could use the FileReference class--for example, to create an interface that browses for a particular SWF file on your hard drive.
When the run-time library is successfully loaded, Flash Player calls the runtimeAssetsLoadComplete() method:
private function runtimeAssetsLoadComplete(event:Event):void
{
var rl:* = event.target.content;
var assetList:Array = rl.getAssets();
populateDropdown(assetList);
stage.frameRate = 60;
}
In this method, the variable rl represents the loaded SWF file. The code calls the getAssets() method of the loaded SWF file, obtaining the list of assets that are available, and uses them to populate a ComboBox component with a list of available assets by calling the populateDropDown() method. That method in turn stores the full classpath of each asset. Clicking the Add button on the user interface triggers the addAsset() method:
private function addAsset():void
{
var className:String = assetNameCbo.selectedItem.data;
var AssetClass:Class = getDefinitionByName(className) as Class;
var mc:MovieClip = new AssetClass();
...
}
which gets the classpath of whichever asset is currently selected in the ComboBox (assetNameCbo.selectedItem.data), and uses the getDefinitionByName() function (from the flash.utils package) to obtain an actual reference to the asset's class in order to create a new instance of that asset.